"""基于JSON的简单持久化助手，用于游戏存档。

此模块提供了保存和加载游戏数据的功能，使用JSON格式存储。
"""

from __future__ import annotations

import json
from pathlib import Path
from typing import Any


# 存档版本号，用于兼容性检查。
SAVE_VERSION = 1


def save_payload(path: Path, payload: dict[str, Any]) -> None:
    """将指定的有效载荷（payload）保存到指定路径。

    参数:
        path (Path): 保存文件的目标路径。
        payload (dict[str, Any]): 要保存的数据字典。
    """
    path.parent.mkdir(parents=True, exist_ok=True)
    temp_path = path.with_suffix(path.suffix + ".tmp")
    with temp_path.open("w", encoding="utf-8") as handle:
        json.dump(payload, handle, ensure_ascii=False, indent=2)
    temp_path.replace(path)


def load_payload(path: Path) -> dict[str, Any]:
    """从指定路径加载有效载荷（payload）。

    参数:
        path (Path): 包含保存数据的文件路径。

    返回:
        dict[str, Any]: 加载的数据字典。
    """
    with path.open("r", encoding="utf-8") as handle:
        return json.load(handle)
